基于 OpenAPI 撰写接口文档

发表于 |

为什么要用 OpenAPI

本来叫“基于 swagger 撰写接口文档”，但是一番搜索阅读之后发现 swagger 已经抽象出了一套接口描述规范，并将其命名为 OpenAPI。在 OpenAPI Specification 的基础上，扩展了很多相关的工具集。
官方的说明文档在此，进一步说明文章网上到处都有。

swagger 工具集包括以下组成部分：

  • 规范 - 整个体系的理论基础。
  • Swagger Editor – 基于浏览器的所见即所得编辑器.
  • Swagger UI – OpenAPI 文件生成交互式 API 文档
  • Swagger Codegen – OpenAPI 文件生成客户端/服务端代码
  • SwaggerHub - 协作平台，在集成了以上开源工具外增加了在线托管、分享等功能
  • Swagger Inspector - 测试 API 和生成 OpenAPI 的开发工具
  • 解决方案 - 组合一个或多个工具（包括其他闭源工具）解决接口的设计、开发、测试过程中遇到的问题
  • 还有基于规范的其他开源工具，可以组合使用，例如导出 md 后再转成 word

如何使用/工作流程

先有接口后生成文档

  1. 整理已有的接口
  2. 生成静态的 OpenAPI spec
  3. 根据 OpenAPI spec 生成文档 / 使用在线的 Swagger UI 生成可交互文档

先有文档再写接口

  1. 在 Swagger Editor 中编写 OpenAPI spec
  2. 使用 OpenAPI spec 生成文档
  3. 使用 OpenAPI spec 生成代码

实战

现在的需求是写一份接口文档，docx ，接口还未实现。
注意：OAS 最新版是 3.0 ，但是很多开源工具只支持到 2.0 ，因此要按照 2.0 来写文档。
导出 md 需要根据文档添加配置。

  1. 在 http://editor.swagger.io/ 完成接口文档撰写
  2. 使用转 markdown 工具得到 md 文件 https://github.com/Swagger2Markup/swagger2markup-cli
  3. 在 http://coolaf.com/tool/md 得到 doc 格式文件
坚持原创技术分享，您的支持将鼓励我继续创作！